package com.kexilo.system.auth.service;

import com.kexilo.core.security.domain.RefreshToken;

import java.util.List;

/**
 * 刷新令牌服务接口
 *
 * @author Kexilo
 */
public interface IRefreshTokenService {

    /**
     * 创建刷新令牌
     *
     * @param userId 用户ID
     * @param accessToken 访问令牌
     * @param deviceId 设备ID
     * @param userAgent 用户代理
     * @param ipAddress IP地址
     * @return RefreshToken
     */
    RefreshToken createRefreshToken(Long userId, String accessToken, String deviceId, String userAgent, String ipAddress);

    /**
     * 根据刷新令牌查询
     *
     * @param refreshToken 刷新令牌
     * @return RefreshToken
     */
    RefreshToken findByRefreshToken(String refreshToken);

    /**
     * 根据访问令牌查询
     *
     * @param accessToken 访问令牌
     * @return RefreshToken
     */
    RefreshToken findByAccessToken(String accessToken);

    /**
     * 验证刷新令牌
     *
     * @param refreshToken 刷新令牌
     * @return 是否有效
     */
    boolean validateRefreshToken(String refreshToken);

    /**
     * 使用刷新令牌生成新的访问令牌
     *
     * @param refreshToken 刷新令牌
     * @param newAccessToken 新的访问令牌
     * @return 是否成功
     */
    boolean refreshAccessToken(String refreshToken, String newAccessToken);

    /**
     * 撤销刷新令牌
     *
     * @param refreshToken 刷新令牌
     * @return 是否成功
     */
    boolean revokeRefreshToken(String refreshToken);

    /**
     * 撤销用户所有刷新令牌
     *
     * @param userId 用户ID
     * @return 是否成功
     */
    boolean revokeAllUserTokens(Long userId);

    /**
     * 获取用户有效的刷新令牌列表
     *
     * @param userId 用户ID
     * @return List<RefreshToken>
     */
    List<RefreshToken> getUserValidTokens(Long userId);

    /**
     * 根据用户ID和设备ID查询令牌
     *
     * @param userId 用户ID
     * @param deviceId 设备ID
     * @return RefreshToken
     */
    RefreshToken findByUserIdAndDeviceId(Long userId, String deviceId);

    /**
     * 清理过期令牌
     *
     * @return 清理数量
     */
    int cleanExpiredTokens();

    /**
     * 清理已使用的令牌（保留指定天数）
     *
     * @param retentionDays 保留天数
     * @return 清理数量
     */
    int cleanUsedTokens(int retentionDays);

    /**
     * 检查用户令牌数量并清理超限的旧令牌
     *
     * @param userId 用户ID
     * @param maxTokensPerUser 每用户最大令牌数
     */
    void cleanExcessTokens(Long userId, int maxTokensPerUser);
}
